Handlers

Each endpoint configuration may be associated with zero or more PRE and POST handler chains.  Each handler chain may include JAXWS handlers.  For outbound messages the PRE handler chains are executed before any handler that is attached to the endpoint using the standard means, such as with annotation @HandlerChain, and POST handler chains are executed after those objects have executed.  For inbound messages the POST handler chains are executed before any handler that is attached to the endpoint using the standard means and the PRE handler chains are executed after those objects have executed.

* Server inbound messages
Client --> ... --> POST HANDLER --> ENDPOINT HANDLERS --> PRE HANDLERS --> Endpoint

* Server outbound messages
Endpoint --> PRE HANDLER --> ENDPOINT HANDLERS --> POST HANDLERS --> ... --> Client

The same applies for client configurations.

Properties

Key/value properties are used for controlling both some Apache CXF internals and some JBossWS options. Specific supported values are mentioned where relevant in the rest of the documentation.

Endpoint configuration assignment

Annotation, org.jboss.ws.api.annotation.EndpointConfig is used to assign an endpoint configuration to a JAX-WS endpoint implementation.  When assigning a configuration that is defined in the webservices subsystem only the configuration name is specified.  When assigning a configuration that is defined in the application, the relative path to the deployment descriptor and the configuration name must be specified.

@EndpointConfig(configFile = "WEB-INF/jaxws-endpoint-config.xml", configName = "Custom WS-Security Endpoint")
public class ServiceImpl implements ServiceIface
{
   public String sayHello()
   {
      return "Secure Hello World!";
   }
}

Endpoint Configuration Deployment Descriptor

Java EE archives that can contain JAX-WS endpoint implementations can also contain predefined endpoint configurations.  All endpoint configuration definitions for a given archive must be provided in a single deployment descriptor file. The file must reside in directory WEB-INF for a web application and directory META-INF for a client and EJB application.  The file name must end with extension .xml and be an implementation of schema jbossws-jaxws-config   Common practice is to use the file name jaxws-endpoint-config.xml but this is not required.

Many endpoint configurations can be defined within the deployment descriptor file.  Each configuration must have a name that is unique within the server on which the application is deployed.  The configuration name is not referencable by endpoint implementations outside the application.

Client configuration assignment

import org.jboss.ws.api.configuration.ClientConfigFeature;

...

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/jaxws-client-config.xml", "Custom Client Config"));
port.echo("Kermit");

... or ....

port = service.getPort(Endpoint.class, new ClientConfigFeature("META-INF/jaxws-client-config.xml", "Custom Client Config"), true); //setup properties too from the configuration
port.echo("Kermit");
... or ...

port = service.getPort(Endpoint.class, new ClientConfigFeature(null, testConfigName)); //reads from current container configurations if available
port.echo("Kermit");

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

...

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);
BindingProvider bp = (BindingProvider)port;
ClientConfigUtil.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 1");
port.echo("Kermit");

...

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 2");
port.echo("Kermit");

...

configurer.setConfigHandlers(bp, "META-INF/jaxws-client-config.xml", "Custom Client Config 3");
port.echo("Kermit");


...

configurer.setConfigHandlers(bp, null, "Container Custom Client Config"); //reads from current container configurations if available
port.echo("Kermit");

import org.jboss.ws.api.configuration.ClientConfigUtil;
import org.jboss.ws.api.configuration.ClientConfigurer;

...

Service service = Service.create(wsdlURL, serviceName);
Endpoint port = service.getPort(Endpoint.class);

ClientConfigUtil.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 1");
port.echo("Kermit");

...

ClientConfigurer configurer = ClientConfigUtil.resolveClientConfigurer();
configurer.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 2");
port.echo("Kermit");

...

configurer.setConfigProperties(port, "META-INF/jaxws-client-config.xml", "Custom Client Config 3");
port.echo("Kermit");


...

configurer.setConfigProperties(port, null, "Container Custom Client Config"); //reads from current container configurations if available
port.echo("Kermit");

Standard configurations

Clients running in-container as well as endpoints are assigned standard configurations by default. Those are used unless different configurations are set as previously described. This way administrators can tune default handler chains for client and endpoints developers did not assign a specific configuration to. The name for such default configuration, to be used in the WildFly webservices subsystem are Standard-Client-Config and Standard-Endpoint-Config.

Handlers classloading

When setting a server-wide handler, please note the handler class needs to be available either through each ws deployment classloader or the org.jboss.as.webservices.server.integration:main module classloader. As a consequence proper module dependencies might need to be specified either in the deployments that are going to leverage a given predefined configuration or directly in the previously mentioned AS7 module.